<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Part 5] 5.2 Reading a Quick Reference Entry</TITLE>
<META NAME="author" CONTENT="David Flanagan">
<META NAME="date" CONTENT="Thu Jul 31 16:05:10 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java in a Nutshell">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java in a Nutshell" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch16a_01.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Part 5<br>How To Use This Quick Reference</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch17_01.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JNUT2-PART-5-SECT-2">5.2 Reading a Quick Reference Entry</A></h2>

<P CLASS=para>
Each class and interface has its own entry in this quick
reference.  These quick-reference entries document the class
or interface as described below.  Because the
information in each entry is quite dense, the descriptions
of it that follow are somewhat complicated.  I recommend
that you flip through the following chapters as you read to
find examples of each of the features described.

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-PART-5-SECT-2.1">Name and Availability</A></h3>

<P CLASS=para>
Each quick reference entry has a title that is the name of the class
or interface it documents.  To the right of
that title, you'll find availability information that
indicates when the class or interface was added to the Java
API.  The string "JDK 1.0" indicates that the class or
interface has been around since the original release of
Java.  The string "JDK 1.1" indicates that it has been added in
the Java 1.1 release, and is therefore not backwards
compatible with Java 1.0 environments.  If the availability
string is followed by the word "Deprecated," it means that
the class or interface has been deprecated and its use is
discouraged.  There are two such deprecated classes in Java
1.1.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-PART-5-SECT-2.2">Description</A></h3>

<P CLASS=para>
The class name is followed by a short description of the
most important features of the class.  This description may
be anywhere from a couple of sentences to several paragraphs
long.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-PART-5-SECT-2.3">Synopsis</A></h3>

<P CLASS=para>
The description is always followed by a synopsis of the
class or interface.  This is a listing that looks like a
Java class definition, except that method bodies and field
initializers are omitted.  This synopsis contains the
following information:

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>Class Modifiers</I><br>
<DD>

<P CLASS=para>
The synopsis begins with a list of class modifiers.  All classes
and interfaces in this quick reference are <tt CLASS=literal>public</tt>;
some are also declared <tt CLASS=literal>abstract</tt> or <tt CLASS=literal>final</tt>

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Class or Interface</I><br>
<DD>

<P CLASS=para>
If the modifiers are followed by the <tt CLASS=literal>class</tt> keyword,
it is a class that is being documented.  If they are
followed by the <tt CLASS=literal>interface</tt> keyword, it is an
interface that is being documented.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Class Name</I><br>
<DD>

<P CLASS=para>
The name of the class or interface follows the <tt CLASS=literal>class</tt>
or <tt CLASS=literal>interface</tt> keyword.  It is highlighted in
bold.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Superclass</I><br>
<DD>

<P CLASS=para>
The superclass of the class follows the <tt CLASS=literal>extends</tt> keywords.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Interfaces</I><br>
<DD>

<P CLASS=para>
The list of interfaces that the class implements, if any,
follows the <tt CLASS=literal>implements</tt> keyword.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Members</I><br>
<DD>

<P CLASS=para>
The constructors, fields, and methods defined by the class
or interface form the bulk of the synopsis.  All
<tt CLASS=literal>public</tt> and <tt CLASS=literal>protected</tt> members are listed.  They are divided
into the following categories, and listed alphabetically by
name within each category.  Each category begins with a
comment to break the synopsis listing into logical sections.
The categories, in the order listed, are:

<P>
<OL CLASS=orderedlist>
<li CLASS=listitem>Public constructors

<P>
<li CLASS=listitem>Protected constructors

<P>
<li CLASS=listitem>Constants

<P>
<li CLASS=listitem>Class variables

<P>
<li CLASS=listitem>Public instance variables

<P>
<li CLASS=listitem>Protected instance variables

<P>
<li CLASS=listitem>Class methods

<P>
<li CLASS=listitem>Public instance methods

<P>
<li CLASS=listitem>Protected instance methods

<P>
</OL>
<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Availability</I><br>
<DD>

<P CLASS=para>
If a member synopsis begins with the string "1.1", it
indicates that the constructor, field, or method has been added
to the class or interface in Java 1.1.  Note that this
indication only appears in classes and interfaces that are
not themselves new in Java 1.1.  If a member synopsis begins
with "#", it means that the constructor, field, or method has been
deprecated in Java 1.1, and that its use is discouraged.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Member Modifiers</I><br>
<DD>

<P CLASS=para>
The modifiers for each member are listed.  These
provide important information about how the members are
used.  The modifiers you may find listed are:
<tt CLASS=literal>public</tt>, <tt CLASS=literal>protected</tt>, <tt CLASS=literal>static</tt>,
<tt CLASS=literal>abstract</tt>, <tt CLASS=literal>final</tt>, <tt CLASS=literal>synchronized</tt>,
<tt CLASS=literal>native</tt>, and <tt CLASS=literal>transient</tt>.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Member Type</I><br>
<DD>

<P CLASS=para>
The listing for a member may include a type.  The types of fields and
constants are shown, as are the return types of methods.  Constructors do
not have return types in Java.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Member Name</I><br>
<DD>

<P CLASS=para>
The name of each class member is in bold, for easy scanning.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Parameters</I><br>
<DD>

<P CLASS=para>
The synopsis for a method or constructor includes
the type and name of each parameter that it takes.  The parameter names
are shown in italic to indicate that they are not to
be used literally.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Exceptions</I><br>
<DD>

<P CLASS=para>
The exceptions that may be thrown by a method or constructor
follow the <tt CLASS=literal>throws</tt> keyword in the synopsis.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Inheritance</I><br>
<DD>

<P CLASS=para>
The synopsis for a method may be followed by a comment that
includes a class or interface name.  If a method is followed
by a <tt CLASS=literal>//Overrides</tt> comment, the method
overrides a method by the same name in the specified
superclass.  If a method synopsis is followed by a
<tt CLASS=literal>//Defines</tt> comment, the method provides the
definition of an <tt CLASS=literal>abstract</tt> method of the specified
superclass.  Finally, if a method synopsis is followed by
a <tt CLASS=literal>//From</tt> comment, the method implements a
method from the named interface (which is implemented by the
class or a superclass).</DL>
</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-PART-5-SECT-2.4">Cross References</A></h3>

<P CLASS=para>
The synopsis section is followed by a number of optional
"cross reference" sections that indicate other, related
classes that may be of interest.  In the first edition of this book,
this information was available in separate index chapters.
We think it should be even more useful when associated
directly with each class and interface entry.  The cross
reference sections are the following:

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>Hierarchy</I><br>
<DD>

<P CLASS=para>
This section lists all of the superclasses of the class, as
well as any interfaces implemented by those superclasses.
It may also list any interfaces extended by an interface.
This section only appears when it provides information that
is not available from the <tt CLASS=literal>extends</tt> and
<tt CLASS=literal>implements</tt> clauses of the class synopsis.  In the
hierarchy listing, arrows indicate superclass to subclass
relationships, while the interfaces implemented by a class
follow the class name in parentheses.  This information can
be useful, for example, to determine whether a class
implements <tt CLASS=literal>Serializable</tt> or <tt CLASS=literal>Cloneable</tt>
somewhere up its superclass hierarchy.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Extended By</I><br>
<DD>

<P CLASS=para>
This section lists all direct subclasses of this class, or
any interfaces that extend this interface, which
tells you that there are more specific classes or
interfaces to look at.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Implemented By</I><br>
<DD>

<P CLASS=para>
This section lists all of the classes that directly implement this
interface, which is useful when you know that you want to
use the interface but you don't know what implementations of
it are available.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Passed To</I><br>
<DD>

<P CLASS=para>
This section lists all of the methods and constructors that are
passed an object of this type as an argument, which is useful
when you have an object of a given type and want to figure
out what you can do with it.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Returned By</I><br>
<DD>

<P CLASS=para>
This section lists all of the methods (but not constructors) that
return an object of this type, which is useful when you know
that you want to work with an object of this type, but don't
know how to obtain one.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Type Of</I><br>
<DD>

<P CLASS=para>
This section lists all of the fields and constants that are of this
type, which can help you figure out how to obtain an object of
this type.

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>Thrown By</I><br>
<DD>

<P CLASS=para>
For exception and error classes, this section lists all
of the methods and constructors that throw exceptions of this type.
This material helps you figure out when a given exception or error may
be thrown.  Note, however, that this section is based on
the exception types listed in the <tt CLASS=literal>throws</tt> clauses of
methods and constructors.  Subclasses of <tt CLASS=literal>RuntimeException</tt> do not
have to be listed in <tt CLASS=literal>throws</tt> clauses, so
it is not possible to generate a complete cross reference of
methods that throw these types of "unchecked" exceptions.</DL>
</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch16a_01.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch17_01.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>Finding a Quick Reference Entry</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>The java.applet Package</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
